3 INSTALLING AND CONFIGURING BTRIEVE This chapter describes how to install and configure Btrieve. It discusses the following topics: o Installing Btrieve o Configuring Btrieve o Starting and Stopping Btrieve o Rebuilding Existing Btrieve Files o Using Btrieve with NetWare Runtime Installing Btrieve The following sections discuss the system requirements and the installation procedure for Btrieve v6.1. System Requirements Make sure your system has the following: o NetWare v3.11 NOTE: Running Btrieve v6.1 in a NetWare v3.11 environment requires AFTER311.NLM, which Btrieve loads automatically. o Adequate memory at the server to load the Btrieve NLM (approximately 528 KB) and the appropriate communications modules. NOTE: The memory required for the communications modules varies, depending on the values you specify for the Largest Record Size and Number of Remote Sessions configuration options. o Adequate memory for the Btrieve Requester at each workstation. Memory requirements vary, depending on the parameters you specify when you load the Requester. These are the default parameters: o The DOS Requester requires approximately 29 KB. o The OS/2 Requester requires approximately 40 KB. o The Windows Requester requires approximately 30 KB. (To use the Windows Requester, you must also have the DOS Requester loaded.) NOTE: Btrieve also provides a requester for the UnixWare environment. For information about this new UnixWare Requester, please refer to the Readme file that accompanies this release. Using the NetWare INSTALL Utility To install Btrieve, complete the following steps: 1. Enter load install at the server console. 2. In response to the Installation Options menu, select Product Options to display the list of currently installed products. 3. Press the Insert key to copy Btrieve v6.x program files to your server. The system responds with the following prompt: Enter drive and/or path to new product source media 4. In response to the prompt, specify the location of the source media. The default response, A; appears in the response field. Use the default if you are installing from the distribution diskette. If you are installing from another source (for example, a NetWare volume and path), enter the source volume and path at this time. If the source media is not on the distribution diskette, the source media you use must have the same directory structure as that found on the distribution diskette. 5. When the Copy Btrieve Files to Fileserver menu appears, select Copy Files. 6. When the Existing Btrieve Program Files menu appears, select either Overwrite or Rename. o Overwrite - This option copies the Btrieve v6.x programs over the existing Btrieve programs. NOTE: The Overwrite option does not overwrite or rename existing Btrieve data files. o Rename - This option renames your existing Btrieve programs so that you can run either the earlier version of Btrieve and Btrieve v6.x. If you choose this option, the utility changes the first letter of the file extension for your existing Btrieve programs to $. For example, program files that had the extension .NLM now have the extension .$LM, and program files with the extension .NCF now have the extension .$CF. 7. When the Insert bstart Into... menu appears, select the appropriate option. o SYS:\SYSTEM\STARTUP.NCF - This option places BSTART.NCF (the Btrieve batch file) into the network's STARTUP.NCF file. o SYS:\SYSTEM\AUTOEXEC.NCF - This option places BSTART.NCF into your server's AUTOEXEC.NCF file. o You Specify Drive, Path, and AUTOEXEC or STARTUP - This option lets you place BSTART.NCF into an AUTOEXEC.NCF or STARTUP.NCF file in a directory other than SYS:\SYSTEM. For example, if you loaded NetWare from a network drive, you might specify that your AUTOEXEC.NCF file be loaded at L:\MYDIR\NW311. o Exit - This option lets you choose to invoke BSTART.NCF manually. If you choose this option, you exit the menu. When installation is complete, the utility displays the following: Program Files Successfully Copied to Fileserver 8. To verify that the correct files are installed on your server, press Esc to return to the Copy Btrieve Files to Fileserver menu and select View Log of files Copied. A list of files copied (similar to the following illustration) appears. Compare this list to the list of files in the release notes that accompany the product shipment. 9. After verifying the copied files, press Esc to return to the Installation Options menu. 10. Select Exit to go to the Currently Installed Products menu. Btrieve is listed as an option under the Currently Installed Products menu. 11. Highlight Btrieve and press Enter to invoke the Btrieve Setup utility. The Available Options menu appears. This menu provides the following options: o Set Btrieve Configuration - Use this option to view or modify the current configuration options for Btrieve. o Set Rebuild Configuration - Use this option to view or modify the current configuration options for the Rebuild utility. ("Rebuilding Existing Btrieve Files" discusses the Rebuild utility and its configuration options.) If you do not want to set configuration options or rebuild Btrieve files at this point, press Esc until you exit the INSTALL utility. After loading Btrieve with the INSTALL utility, you can configure Btrieve according to your Btrieve application's requirements. Use the guidelines discussed in the next section, "Configuring Btrieve." You can then activate Btrieve as discussed in "Starting and Stopping Btrieve." Configuring Btrieve You can configure Btrieve by setting configuration options. When you load Btrieve with the INSTALL utility, these options are set to their default values. (Table 3-1 shows the default values.) However, your Btrieve application may require different values for these options. To determine which values your application requires, refer to the documentation included with that application. Table 3-1 - Default Values for Configuration Options Configuration Option Default Value Number of Open Files 20 files Number of Handles 60 handles Number of Locks 20 per client Number of Transactions 15 transactions Largest Compressed Record Size 0 KB Largest Record Size 8,192 bytes Largest Page Size 4,096 bytes Number of Remote Sessions 15 sessions Cache Allocation 256 KB Perform Index Balancing No Logging of Selected Files No Create Btrieve Files in Pre v6.x Format No Create Files as Transactional No Configure BSTART.NCF to Load BROUTER No The following section discusses each configuration option individually. You can change the values for the configuration options by running the Btrieve Setup utility (as described in "Running the Setup Utility"). The Setup utility stores your changes in the BSTART.NCF NetWare command file. Configuration Options This section lists the Btrieve configuration options in the order in which they appear in the Setup utility. For each option, the discussion includes the following: o Range of acceptable values o Default value o Approximate memory required o Description of the option Number of Open Files Range: 1 through 64,000 files Default: 20 files Approximate Memory Required: 425 bytes per file This option specifies the maximum number of unique Btrieve files that can be open at one time at the server. The value you specify determines the size of the internal tables used to track active files. Each unique Btrieve file on the server counts as one file. Number of Handles Range: 1 through 64,000 file handles Default: 60 handles Approximate Memory Required: 200 bytes per handle This option specifies the maximum number of file handles that the Btrieve NLM can use at one time. Keep in mind that the number of handles is different from the number of open files. That is, if two sessions open the same file on the same server, Btrieve counts it as one open file, but two different file handles. See "Number of Locks" (next) for a definition of sessions. Number of Locks Range: 0 through 64,000 locks Default: 20 locks per client session Approximate Memory Required: 20 bytes per lock This option sets the maximum number of records a client session can lock at the server at one time. (A session occurs when a client uses the Btrieve Requester or Message Router to communicate with the Btrieve NLM, or when an NLM application calls Btrieve directly.) This maximum applies to whichever type of read lock (single record or multiple record) the client session is using. Single-record locks allow an application to lock only one record at a time. Multiple-record locks allow an application to lock more than one record at a time. Number of Transactions Range: 0 through 64,000 transactions Default: 15 transactions Approximate Memory Required: 20 bytes + (2 * maximum number of files) This option sets the maximum number of Btrieve clients that can simultaneously have active transactions at the server. (Each of these clients can have only one active transaction at the server.) For example, if you specify 6 transactions, Btrieve creates a transaction file at the server (BTRIEVE.TRN in the SYS:SYSTEM directory) and allows a maximum of 6 clients to have one active transaction each at the server. If you specify a value of 0, no clients can perform a Btrieve transaction. Largest Compressed Record Size Range: 0 through 64 KB Default: 0 KB Approximate Memory Required: 2,048 bytes * specified value This option allows you to allocate memory for a compression buffer that Btrieve can use when you access records in a Btrieve file created with the Data Compression file attribute enabled. Btrieve allocates a compression buffer with a size of 2,048 bytes multiplied by the value you specify for this option. Use the following guidelines when specifying the value for this option: o If you use compressed Btrieve files, determine the size (in bytes) of the largest record in any of your compressed files. Round the record size to the next whole kilobyte. For example, if the largest record you need to access is 1,800 bytes, specify 2 for this option. Btrieve will allocate 4,096 bytes (that is, 2,048 * 2) of memory for the compression buffer. o If every compressed file you use has Variable-tail Allocation Tables (VATs), set this option to the file's largest page size (in bytes) divided by 128. For example, if the largest page size is 1,024 bytes, specify 8 for this option. Btrieve will allocate 16,384 bytes (that is, 2,048 * 8) of memory for the compression buffer. o If you do not use compressed files, set this value to 0. You cannot improve performance, and may waste memory, by specifying a value higher than you need. Largest Record Size Range: 600 through 64,000 bytes Default: 8,192 bytes Approximate Memory Required: recordLength * (remoteSessions /5) + 1 + (remoteSessions * recordLength / 580) * 600 recordLength 538 + largest record size remoteSessions Number of remote sessions This option specifies the length of the largest record or record chunk that any remote Btrieve application (excluding other NLMs that call Btrieve, such as NetWare SQL) can access at the server. A record chunk is any arbitrary portion of a record, specified by its offset and length. Specify the length of the record (or record chunk) in bytes. Specifying a value higher than you need does not improve performance and may waste memory. NOTE: For applications running on workstations, the maximum record length is 57,000 for the DOS Requester, 65,000 for the OS/2 Requester, and 57,000 for the Windows Requester. Largest Page Size Range: 512 through 4,096 bytes Default: 4,096 bytes Approximate Memory Required: Not applicable This option specifies the maximum page size (in bytes) of any Btrieve file you want to access. The page size must be a multiple of 512 bytes, but no greater than 4,096 bytes. Setting the page size to 512, 1,024, 2,048, or 4,096 can improve performance because these page sizes correspond to disk block sizes. If you set the page size to 1,536, 2,560, 3,072, or 3,584, a given disk read may span two disk blocks and therefore require two disk accesses per page. Number of Remote Sessions Range: 1 through 64,000 sessions Default: 15 sessions Approximate Memory Required: 150 bytes * number of remote sessions This option specifies the maximum number of SPX sessions that can access the remote Btrieve NLM at one time. (A session occurs when a client uses the Btrieve Requester or the Message Router to communicate with the remote Btrieve NLM.) Each session is allocated two packet buffers for Btrieve requests. NOTE: If you receive a Status Code 96, increase the value for this option. However, do not specify a value higher than you need. Specifying a value that is too high does not improve performance; instead, it uses memory that NetWare or other processes might need. Cache Allocation Range: 32 through 64,000 KB Default: 256 KB Approximate Memory Required: Not applicable This option specifies the size of the cache (in kilobytes) that Btrieve allocates. To achieve best performance, allocate a cache size equal to the sum of the sizes of the files you are using. However, be careful not to take all available cache, especially if the server is running other applications. You cannot improve performance, and may waste memory, by specifying a value higher than you need. Perform Index Balancing Range: Yes or No Default: No Approximate Memory Required: Not applicable When an index page becomes full, Btrieve automatically creates a new index page and splits the values in the full index page between the two index pages. The Perform Index Balancing option lets you avoid creating a new index page every time an old one fills up. If you specify Yes for this option, Btrieve looks for available space in sibling index pages each time an index page becomes full. Btrieve then rotates values from the full index page into the pages that have space available. Index balancing increases index page utilization, results in fewer index pages, and produces an even distribution of keys among nodes on the same level, thus increasing performance during Get operations. However, when you specify Yes for this option, Btrieve requires extra time to examine more index pages and may require more disk I/O during Insert, Update, and Delete operations. NOTE: You can also specify index balancing on a file-by-file basis by setting a bit in the file flagÕs word when the file is created. If you specify Yes to the Perform Index Balancing option, Btrieve performs index balancing on every file regardless of the balanced file flag specification. Logging of Selected Files Range: Yes or No Default: No Approximate Memory Required: Not applicable This option controls whether Btrieve logs operations executed on selected files. If you specify Yes, Btrieve logs all operations that change any file listed in the BLOG.CFG file on BtrieveÕs server volume. If you specify No, Btrieve performs no logging. For more information on logging and the Roll Forward utility, see Chapter 5, "Using Btrieve Utilities." Create Btrieve Files in Pre v6.x Format Range: Yes or No Default: No Approximate Memory Required: Not applicable This option specifies that all files be created in a Btrieve version prior to v6.x. Use this option only if you need backward compatibility with a previous version of Btrieve. For example, if you want to create files with Btrieve v6.x and you want to use those files with Btrieve v5.x, specify Yes for this option. NOTE: Btrieve v6.x can read files that previous versions of Btrieve created. In addition, it can write to files using the existing file format. In other words, it writes to v5.x files using the v5.x format and writes to v6.x files using the v6.x format. Create Files as Transactional Range: Yes or No Default: No Approximate Memory Required: Not applicable This option controls whether Btrieve automatically flags each file as transactional when you create it. The transactional flag indicates that the NetWare Transaction Tracking System (TTS) is protecting the file. TTS ensures that, when a file is being modified, either all changes are made or no changes are made, thus preventing data damage. Configure BSTART.NCF to Load BROUTER Range: Yes or No Default: No Approximate Memory Required: Not applicable This option controls whether the Message Router is loaded during the execution of the BSTART.NCF NetWare command file. The Message Router allows other NLMs (such as NetWare SQL) to communicate with remote servers on which Btrieve is loaded. If you want to access Btrieve data on a remote server, specify Yes for this option. Running the Setup Utility Use the Setup utility to set the Btrieve configuration options interactively. The utility automatically checks to see if the values you enter are within the correct ranges. You can run the Setup utility either at the server console or at a workstation running the NetWare Remote Console utility (RCONSOLE). To run the Setup utility, complete the following steps. NOTE: To get help with the Setup utility, press F1. The help information is context sensitive, relevant to your location in the program. To exit the utility, press the Esc key. 1. Enter load bsetup at the prompt to start the utility. If your SYS:SYSTEM directory does not contain the BSTART.NCF command file, the Setup utility displays a window asking if you want to create it. If that window appears on your screen, create the BSTART.NCF file at this time. The Available Options menu appears. This menu provides the following options: o Set Btrieve Configuration - Use this option to view or modify the current configuration options for Btrieve. o Set Rebuild Configuration - Use this option to run the Rebuild utility, view or modify the current Rebuild configuration options, and view the Rebuild log file. ("Rebuilding Existing Btrieve Files" discusses the Rebuild utility and its configuration options.) 2. To change configuration options, select Set Btrieve Configuration. 3. When the Current Btrieve Configuration screen appears, use the Up- and Down-Arrow keys to highlight the configuration option you want to change, and press the Enter key. A flashing cursor appears. 4. Use the Backspace key to remove the old value; then, type the new value and press the Enter key. If you enter an invalid value for an option, the utility displays a message indicating the valid values. NOTE: To see the valid values for any option, move the cursor to that option, press the Enter key, and then press the F1 key. You can also refer to "Configuration Options" for more information about these options and their values. 5. Repeat Steps 3 and 4 until you have changed all the options you want to modify. 6. When you are ready to exit the Current Btrieve Configuration screen, press the Esc key. 7. When the Save Configuration Changes? screen appears, select Yes to save your changes or No to abandon the changes. If you select Yes, the Setup utility writes the configuration values you specified to the BSTART.NCF file. IMPORTANT: Do not edit the BSTART.NCF command file for Btrieve. Always use the Setup utility to make any modifications to the configuration values in the BSTART.NCF file. Before your configuration changes can take effect, you must unload the existing Btrieve NLM, BSPXCOM, and the Message Router (using the BSTOP command), and then reload them by entering the BSTART command. BSTOP.NCF does not unload BSPXSTUB or RSPXSTUB. To unload these modules, type UNLOAD followed by the module name. 8. To exit the Setup utility, press the Esc key until the Exit window appears, and then select Yes. Starting and Stopping Btrieve This section discusses starting and stopping Btrieve. Before starting Btrieve v6.x, you must first check for any extraneous pre-image files (files with a .PRE extension) and then unload the earlier version of Btrieve. NOTE: If you need to preserve your Btrieve v5.x files, you can use Btrieve v6.x to read them. Checking for Extraneous Pre-Image Files If you have any extraneous .PRE files in your database, you must remove them before starting Btrieve v6.x. The following procedure explains how to check for and remove extraneous .PRE files. IMPORTANT: You must have Btrieve v5.x or v6.0 loaded before performing these steps. 1. Using your existing version of Btrieve (such as v5.x or v6.0), open the Btrieve data file corresponding to the .PRE file in Exclusive mode. 2. Perform a Get First operation. 3. Perform an Update operation (this will not change the record). 4. Close the Btrieve data file (this should cause Btrieve to delete the .PRE file). 5. Any .PRE files that remain for the designated file after you perform Steps 1 through 4 are extraneous. Delete them at this time. 6. Repeat Steps 1 through 5 to find and delete any other extraneous .PRE files. IMPORTANT: If you do not remove the extraneous .PRE files before starting Btrieve v6.x, file corruption may occur.